Add credential fill, vaults, TOTP and 1Password tokens, with LLM tools - #142

Adds browser credential fill, vaults and typed secrets to the sync and async clients, plus fill_credential tool definitions for OpenAI, Anthropic and Gemini. It matches browserctrl master at 08c5d5232: #1572 (fill on plain secrets), #1551 (vaults), #1552 (op_token, per-request 1Password fields and 1Password browser fill) and #1573 (totp). It mirrors node-sdk#131.

The credential secret type from #1537 is gone. A login is plain secrets that have allowed origins, usually grouped in a vault (USERNAME, PASSWORD, and optionally OTP from a totp secret). Values are encrypted locally and typed into pages by the platform, so neither the caller's code nor an LLM ever sees them.

API (sync and async; params as dicts or models)

Secrets

• client.secrets.create({name, value?, description?, type?: "secret" | "totp" | "op_token", allowed_origins?, metadata?})
  • Values are checked locally per type before anything is created.
  • totp: a base32 seed or an otpauth://totp/ URI. The parsing mirrors vm-service's parseTOTPSeed: spaces, hyphens and line breaks are ignored, = padding is allowed only at the end, and lengths 1, 3 or 6 past a multiple of 8 are refused. In a URI, algorithm, digits and period are range-checked, and HOTP is refused.
  • op_token: a 1Password service account token, named by one_password.token. It takes no allowed origins.
• add_version(secret, value) checks the value against the secret's stored type.
• set_allowed_origins(secret, origins | None), update(secret, {description?, metadata?}) and list({type}).
• Secret.type is a plain string.
• create_credential and object values are removed.

Vaults (new client.vaults, by ID or exact name)

• list, get, delete.
• create({name, description?, entries?}) and update(vault, {description?, entries?: {ENV: StoredEntry | None}}), where None removes an entry. Vaults hold stored secrets only, as on master; the params are strict, so a leftover source or {item, field} entry is refused rather than dropped.

Sandboxes

• vault on create (image launches), exec and processes.start. secrets wins on a clash.
• one_password=OnePasswordSource(token, vault, fields={ENV: OnePasswordField(item, section, field)}) (or a dict) on the same calls reads fields of a 1Password vault when the process starts; it's sent as onePassword.
• Bindings have optional name, secret_id and version, plus secret_type, reference, token_secret, source (vault, secrets or onePassword) and overrides.
• The handle keeps startup_secrets across refreshes.

Sessions

• credentials: [str | {"secret": ...} | {"vault": ...} | {"one_password": ...}] on create. {"one_password": "op-token"} (sent as onePassword) attaches an op_token so fills can read 1Password fields.
• client.sessions.credentials.fill(session_id, {credential? | vault?, fields: [{selector, field?}], page_id? | page_url?, frame_url?})
  • It returns version, page_id, origin and fields[selector, outcome, secret_id, version, field, expires_at].
  • The request is checked locally, and the timeout is at least 30 s.
• 1Password fill: fill(session_id, {"one_password": {"token", "vault", "allowed_origins"}, "fields": [{"selector", "ref": {"item", "section", "field"}}]}). Field results gain reference, and there's no top-level version. Checked locally like node.
• The event log types gain credential_filled and credential_fill_refused.

Tools: CredentialFillTool / fill_credential (OpenAI strict, Anthropic, Gemini)

• It has the same inputs as node: credential, vault, fields[{selector, field}], page_id, page_url and frame_url.
• None and "" count as absent, and input that isn't an object returns invalid_request JSON.
• It doesn't offer 1Password fills: those name their allowed origins in the request, and a model shouldn't choose them. Apps call fill directly.
• Results and errors never contain values.

README: the secrets, vaults and credential fill section is rewritten. It covers onePassword, error codes and the tool loops.

Validation split: the SDK checks request shapes, secret values (UTF-8, size, no NUL) and TOTP seeds locally, since the API can't see an encrypted value. Policy rules (allowed-origin syntax, 1Password names and the 512-byte reference, field and entry limits, source clashes) are left to the API, which returns its status, code, retryable flag and details unchanged. See docs/credentials-cleanup.md.

Version

The package is bumped to 1.13.1 (published: 1.12.1).

Validation

• Local checks: after the rebase onto main and the validation cleanup, 1004 tests pass on Python 3.12 (including the mypy and Pyright typing tests) and 1000 on 3.8. Ruff is clean.
• Audit against master 08c5d5232 (before the validation cleanup): every request, response, error and README claim was checked against the merged server. Fixes:
  • variable names are limited to 256 characters;
  • README: the frame_url tab rule, SECRET_ONEPASSWORD_AUTH_FAILED for malformed tokens, and the 503 variants.
• End to end (before the validation cleanup): 33/33 checks passed against a local stack running #1552 and #1573:
  • secrets with origins;
  • TOTP create, with bad seeds refused locally;
  • a vault with USERNAME/PASSWORD/OTP, and a session with [{"vault"}];
  • vault and single-secret fills; the typed TOTP code matches a locally computed one;
  • the ambiguous-tab retry and origin refusal;
  • a real login, the event log, and async calls.
• Model loop: one gpt-5-mini loop filled by vault, recovered from CREDENTIAL_PAGE_AMBIGUOUS with page_id, and logged in.
• TOTP parsing: compared with #1573's parseTOTPSeed (including its line-break fix, 456995310) on 143 edge cases, alongside node-sdk, hx and the dashboard: no differences.
• 1Password, live (run before the validation cleanup; not repeated since): 25/25 checks passed against the same stack with a real 1Password service account:
  • one_password on sandbox create (the startup command, read through startup_secrets), exec and processes.start; the values matched by hash;
  • the bindings and the clash, missing-item and wrong-type errors;
  • 1Password fill with origin, not-attached and missing-item refusals, then a real login on scrapingcourse.com;
  • no response contains the token.

Needs browserctrl #1552 and #1573 (both merged) to be deployed for op_token, one_password and totp.

🤖 Generated with Claude Code

https://claude.ai/code/session_019dbwbLvQGyzwkxNetvqf3v